Post by Dutch Owen on Sept 4, 2019 8:15:36 GMT -5
Captains,
Some of you are getting deep enough into FSCAI to start to try and add weapons and vehicles. Here are some general tips on how to do that. The UI should be easy enough to use so there's no need to cover that here. Instead we talk about general topics.
First you'll notice that to create a new weapon or vehicle you must first select another one into the edit dialog. This is deliberate. It makes no sense to start "from scratch" with a blank slate. When creating a new weapon or vehicle find one that's already in the database that's close to what you want or at least the same basic type, double-click on that, then modify the name to the new name you want to give it and change whatever else you need to change then click on "Add New Weapon" or "Add New Vehicle" as the case may be. If you're adding a new air-to-air missile, pick an existing air-to-air missile and so on.
Second, always remember that whatever you create is for the use of AI pilots. The numbers you give not only give the weapons operating parameters but they are also used by the AI pilots to make decisions. You'll need to research each new weapon to get its specifications, but please resist the urge to put the quoted "maximum limit" numbers in as the numbers to use for FSCAI. This is because the numbers you find on the Internet are often right out of the sales brochure and we all know how truthful they are. Often a Wikipedia article will mention the practical maximums versus the sales claims. Always go with the practical not the theory. Otherwise you risk defining weapons with unrealistic capabilities. I never use sales brochure numbers - I always reduce them to a reasonable practical limit. This is especially true of missiles, where the manufacturer (or the using Air Force) often claim performance and range that's seldom seen in the real world.
Third, always consider balance. Try not to define weapons that are so powerful that they give the user of that weapon an overwhelming advantage. Also be wary of setting numbers like accuracy and potency too low or too high, you can easily gimp a weapon to the point of uselessness or make it into science fiction rather than realistic.
Weapons Details
Each weapon name obviously needs to be unique, and keep it short. You'll be using it often when you attach it to vehicles.
Every weapon has a type. For those that do damage the codes are GUN, ROCKET, BOMB, or MISSILE. There is one special code here: RADAR. This defines a radar device that will be used by the AI pilot to detect enemy aircraft based on the range, altitude, and visibility cone values define below.
Regarding the maximum and minimum ranges and altitudes - remember the paragraph above about not putting in unrealistic numbers either too high or too low. AI pilots look at these numbers to decide what weapon to use when and also they greatly influence the calculations for maneuvers since the whole point of air combat is to get within weapons range.
Visibility Cone is quite important. Specifically this is the degrees left or right of the aircraft's current heading in which the weapon can be used. For example, if this cone is defined as 20, then if the aircraft's heading is 200 then the weapon can be used on any enemy (otherwise within range) from a bearing of 220 to a bearing of 180 from the airplane's nose. Typically for ground weapons this cone is 180, which is the maximum number here, representing 360 total degrees. For aircraft this is rarely the case because aircraft weapons are restricted - the only exception usually being the rotating turrets on many vintage level bombers. Aircraft guns have narrow cone of 5 to 10 degrees. For missiles this is particularly important as it limits the firing azimuth - older air-to-air missiles have narrow numbers and newer ones have higher numbers but no missile will have a cone greater than about 50. An AIM-9B or a Shrike will have a very narrow cone of 5 to 10. You can make this number negative, in which case the cone line is behind not ahead of the aircraft. This can be useful for some aircraft that have rear-facing guns.
The Burst, Rounds and Reload data items have a profound effect on what happens when the weapon is fired. FSCAI vehicles (air or ground) take "shots", and roughly at a rate of one "shot" per second. "Burst" is the number of rounds expended per shot, and "Rounds" is the number of rounds in a "magazine." Be aware this applies not only to guns but all weapons. Once the rounds are expended then for a ground vehicle they will have to pause to reload (this gives the targets a short respite) and the "Reloads" data item gives the number of times the magazine can be reloaded until the vehicle is "out of ammo" and has to be re-supplied, which is a lengthy amount of downtime. Aircraft do not get any reloads, when their "Rounds" are used up they are out of ammo even if you give a "Reloads" number for a weapon (remember the same weapon can be attached to an aircraft or a ground vehicle.)
There are some special rules around "Burst" and "Rounds" when talking about bombs to reproduce the way they are dropped in the real world. The "Rounds" is always simply the number of bombs the aircraft is carrying. But "Burst" has some special meaning and this depends on the "Role code" of the aircraft doing the bombing. In short, Attack (A) and Dive Bombers (DB) work differently from Level Bombers (LB). For A and DB types, a "Burst" of 1 means one bomb will be dropped from the centerline store on each attack pass. A "Burst" of 2 means a pair will be dropped from the wings. And any "Burst" above 2 means that number will be dropped per pass from the centerline store. For LB (Level Bomber) roles a "Burst" of 1 means to drop all the bombs in the magazine from the center on the first pass over the target. Any "Burst" above one means to drop that many bombs from the center on each pass.
Accuracy and Potency: These two define how effective the weapon really is. Accuracy is roughly the percentage of the time any shot at the weapon's maximum range will score a direct hit. It is rough because anything can miss. But an accuracy of 100 is extreme - it means the weapon would almost never miss even at maximum range. For guns this accuracy will scale up based on distance such that at a range of 100 meters it will be 100% for for them a low initial maximum range number here would be appropriate. For rockets and bombs this is not relevant - they will either hit or miss based on ballistics. For a missile this is the success rate, in the sense that success means no malfunction will occur. For example a missile with an "accuracy" of 75% would experience guidance or other failures on 25% of shots taken with it. This doesn't mean they will always miss when they fail but the odds of a hit are significantly reduced depending on when in the flight path to the target the failure occurs. It doesn't mean they will always hit when there is no malfunction either - evasive maneuvers and/or countermeasures can still foil them.
Potency is the amount of damage inflicted by a direct hit expressed as a percentage, from 1 to 200. Why over 100? because of the "mitigation" factor on vehicles (see below) that simulates armor. A weapon with a potency of 100 scoring a direct hit on a vehicle with a mitigation of 40 means a 60% hit not a 100% hit. Therefore the maximum is 200, which is a number that will destroy any vehicle in one shot regardless of its mitigation. Any number over 100 is extreme but justified in the case of big bombs like 2000LB and above. This is because of blast radius.
Blast Radius is the diameter of a circle around the impact point of a round in which any SimObject will take damage. The damage is calculated realistically based on distance and the way this is done is to scale the potency. This is why the potency number is for a direct hit. The damage scale is not linear - an object at a distance 50% of the blast radius will take less than 50% of the damage, but it will take some. We should note here the effect of secondary explosions. Any time a truck type vehicle is destroyed there is a random chance that the truck contained ammo, and that ammo may cook off and detonate some time after the initial explosion. This creates another blast radius equivalent to a 500LB bomb. Which in turn can affect other nearby objects and cause more damage which could result in more secondaries and so on. This is why trucks shouldn't be parked close together, ever. But in real life they are sometimes. Further, any time a fuel truck is damaged more than 10% it too will explode in a fireball which again causes secondary damage. The fire will burn for a long time. This is also true for aircraft on the ground which can randomly be loaded with bombs and also have lots of fuel on board. When a bunch are parked together a single bomb hit can cause massive havoc.
SimObject Title is the name of an actual object in the game that will be spawned to visually represent a round from the weapon. Be cautious in the use of this field! Every spawned object costs time and too many can make your sim stutter or even crash. When too many effects are onscreen odd graphic effects sometimes happen. As designers we want to keep performance up so don't put a title on a weapon unless you really need to. A title of "*" means the weapon shoots "invisible bullets" and this is good - no objects are spawned, the program instead calculates the probability of hit or miss based on many factors and inflicts damage based on the results but the amount of time for these calculations is a tiny fraction of the performance hit of having an object flying through the air - because for the sim, every object even tiny nearly invisible ones is an airplane and is treated like an AI airplane piloted by a pilot.
Use the title for missiles, rockets or bombs. In the case of a gun carefully consider whether we need to see tracers coming from it. If it's defined as a "Flak" gun in the special flag code FSCAI will provide the flak explosions as well as calculate the hit percentage based on the accuracy data item. If it's not "Flak" then if you use the "*" FSCAI will not spawn any object so you won't see tracers. If you provide a title to a non-Flak gun then the "Burst" number of tracers will be released each shot. When this happens the program doesn't use its hit probability calculations at all, instead it tracks the tracer and if it hits damage is done (based on Potency) and if it misses, it misses. The "Accuracy" number in this case is used to introduce aiming errors. This is why sometimes "accuracy" is a very rough guide.
Vehicles Details
A vehicle is anything that can move. It can be a truck, tank, ship, or airplane or anything that has an engine.
For any SimObject in the sim world to shoot it must be listed in the FSCAI Vehicle database. What it shoots and how it shoots it depends on the weapon or weapons attached to it, selected from the weapons database. FSCAI does not try to enforce realism. You can define ridiculous weapons and attach them to inappropriate vehicles, the program doesn't care. It's entirely up to you to provide realistic or at least plausible vehicle and weapon definitions.
Vehicle definitions are simple. There aren't too many data items. This causes you to think generically instead of getting lost in details, which is so easy to do in the complex and arcane world of military hardware. Remember what we said at the beginning: KISS: keep it Simple. This database is to serve the purposes of a plausible and realistic AI, not to document the details of real-world weapons. I will repeat that. This database is to serve the purposes of a plausible and realistic AI, not to document the details of real-world weapons.
Resist any urge to get too specific or detailed. It will just make life more complicated for everyone.
The most vital concept to understand is how FSCAI links up a SimObject to a vehicle definition. Every SimObject in the sim world has a data item called Title. The title for each aircraft is defined in the aircraft.cfg file, and for a non-aircraft it's defined in the sim.cfg file. For non aircraft FSCAI uses this title to link to a vehicle. For an aircraft the rule is different (there are good reasons for this.) Every aircraft in the sim world also has an "atc_model" code assigned to it in the aircraft.cfg. As far as the sim goes this "atc_modeL' is used to help the built-in ATC system call the airplane by it's right model. For example a model code of "B737" would allow the ATC controllers to say "seven thirty seven" when they refer to the aircraft. Because this model code is the closest thing to a type of aircraft we have available to us, FSCAI uses it to link to aircraft vehicle types in the database.
If we used the "Title" then every single livery or paint would have to be defined in the database. But by using the model we get around this: a "P51" is a "P51" regardless of how it's painted. Why not use the model code for ground vehicles then? Because the sim.cfg fiel they are defined with typically does not allow an "atc_model" to be defined for them. We have to use Title, but this is not a major problem because there are rarely multiple paints for ground vehicles in practice.
Therefore because of this, aircraft and non-aircraft are defined a little differently. Let's talk about aircraft first.
Every vehicle has an official name and it must be unique but you can use anything you want in this field. I recommend keeping it short.
After the official name you must list the atc_model for this aircraft definition. It should be unique too -- there is no point in defining the same model twice, only the first would ever be used. This is used to match to the atc_model defined in the aircraft.cfg as mentioned above. No match, no weapons. You will need to look in the aircraft.cfg for "atc_model=" for new airplanes and use the code there, or change it in that file to match.
For an aircraft the vehicle type must be aircraft - obviously.
Damage Mitigation is rarely used for aircraft, they are all pretty fragile. For some that have a reputation of being tough I put a small number here like 5. This will prevent a weapon with a potency of 100 (for example a missile) from outright destroying it with one hit. It will be almost destroyed at 95% but still can be flown. Beware putting higher numbers in here - even "tough" aircraft will fall to a direct hit from most missiles.
Normal cruising speed isn't really used - we use the design cruising speed defined in the aircraft.cfg instead. But you need to put something reasonable here, because it will be used if the speed in the aircraft.cfg is missing or unreasonable (which some actually are).
Visibility Cone is quite important. Specifically this is the degrees left or right of the aircraft's current heading in which the pilot can normally see another aircraft. This is a major factor in finding enemies and avoiding disaster. Remember this is the degrees to the left and to the right, not both! The maximum value is 180, which would be a 360 degree circle with no blockage. This is not realistic! Almost every airplane has some blockage to the rear vision, even with mirrors - and mirrors distort and aren't effective unless the enemy is close behind you. Some aircraft have more than others - for instance the famous MiG-21 has very poor rear visibility. Thus is is defined with a restrictive cone of 110, whereas a more modern bubble cockpit has a typical cone of about 160. This is not an absolute block! All pilots can "check six" periodically (rate determined by their skill rating) but if an enemy is within this cone he will be picked up much quicker.
The Role Code is used to generically define the aircraft's combat role. Since aircraft don't use a Title to match up we have taken over this data item for the Role Code. The purpose of this code is so the AI pilot can understand the typical combat role his aircraft plays. This affects many of his decisions and defining an appropriate role code is vital. The codes are:
- A - Attack Aircraft. This is an aircraft designed to strike ground targets. Although it may have some defensive air-to-air capabilities that's not its purpose and not what it's good at. Examples would be most US aircraft whose model starts with "A" like the A-1 Skyraider, A-4 Skyhawk, or A-10 warthog. Or the Russian Su-25 is another good example. It will always have a primary air-to-ground weapon defined and usually many more.
- F - Fighter Aircraft. This is designed to shoot down other aircraft in an air superiority role. It will always have a primary air-to-air weapon defined and often more on modern airplanes.
- FB - Fighter/Bomber. One that swings both ways. Typically a jack of both trades but master of neither. It can be difficult to decide between F and FB for some aircraft, like the P-51 which served both roles. It's not a huge deal which you pick actually.
- DB - Dive Bomber. An Attack aircraft that uses a steep dive as its primary method of bomb release. A Stuka or Douglas Dauntless or many other examples.
- LB - Level Bomber. An Attack aircraft that's designed to release typically large bomb loads in level flight.
- T - Transport. A typically unarmed transport aircraft, usually large. It may have defensive weapons which is why we allow it to be defined here. An AWACS aircraft would be defined as a T type, but would be equipped with a radar device for detection of enemy aircraft.
Vehicle Weapons - this is where you list the weapons attached to the vehicle. There are 8 "slots". Slot #1 should be reserved for the primary air-to-air weapon, and slot #2 should be reserved for the primary air-to-ground weapon. Either can be used for any weapon however. Weapons are selected by the AI pilot in a primary order defined by the slot position. Lower slots are selected over higher numbered ones. Only when a lower numbered slot is out of ammo or out of range will an AI pilot select a higher numbered one.
Now we'll talk about ground vehicles - which includes ships.
These vehicles don't use the atc_model code to match up, so that data item can be used for a "Short name".
The "Vehicle Type" can be a wide select; anything but "Aircraft". This isn't used much in the present release, but when we start to have ground vehicles engaging one another it's going to matter a great deal.
Damage Mitigation is very important for ground vehicles - it's how we distinguish between soft and hard targets. A truck has zero mitigation, whereas a tank could have up to 50 or more. Be wary of extreme numbers here. Remember this is matched against weapon potency to determine damage in a direct hit. For example let's say an AGM-65 Maverick has a potency of 100. Let's also say a tank that it targets has a mitigation of 50. That means a direct hit by the Maverick would reduce the tank by 50%, barely disabling it but it would survive. That's not totally unrealistic, although a mitigation for 30 or 40 would be better. A mitigation of 80 would allow a vehicle to not only survive a direct AGM-65 hit but not even be disabled - NOT realistic.
Cruising speed is important for surface vehicles, as we have no other source for this number.
Visibility Cone works just like it does for aircraft, but typically it is 180 for ground vehicles specially anti-aircraft weapons.
The "Role Code" data item for aircraft is the SimObject Title for ground vehicles. This is used to weaponize a particular ground vehicle or ground of vehicles with the same title in the same world. No match, no shooting. This title can be found in the sim.cfg in the vehicle's folder, or sometimes a ground vehicle is defined as an aircraft - in this case look in the aircraft.cfg. In both cases what you are searching for is "Title=" - case doesn't matter.
I hope this has been useful.
Dutch
Some of you are getting deep enough into FSCAI to start to try and add weapons and vehicles. Here are some general tips on how to do that. The UI should be easy enough to use so there's no need to cover that here. Instead we talk about general topics.
First you'll notice that to create a new weapon or vehicle you must first select another one into the edit dialog. This is deliberate. It makes no sense to start "from scratch" with a blank slate. When creating a new weapon or vehicle find one that's already in the database that's close to what you want or at least the same basic type, double-click on that, then modify the name to the new name you want to give it and change whatever else you need to change then click on "Add New Weapon" or "Add New Vehicle" as the case may be. If you're adding a new air-to-air missile, pick an existing air-to-air missile and so on.
Second, always remember that whatever you create is for the use of AI pilots. The numbers you give not only give the weapons operating parameters but they are also used by the AI pilots to make decisions. You'll need to research each new weapon to get its specifications, but please resist the urge to put the quoted "maximum limit" numbers in as the numbers to use for FSCAI. This is because the numbers you find on the Internet are often right out of the sales brochure and we all know how truthful they are. Often a Wikipedia article will mention the practical maximums versus the sales claims. Always go with the practical not the theory. Otherwise you risk defining weapons with unrealistic capabilities. I never use sales brochure numbers - I always reduce them to a reasonable practical limit. This is especially true of missiles, where the manufacturer (or the using Air Force) often claim performance and range that's seldom seen in the real world.
Third, always consider balance. Try not to define weapons that are so powerful that they give the user of that weapon an overwhelming advantage. Also be wary of setting numbers like accuracy and potency too low or too high, you can easily gimp a weapon to the point of uselessness or make it into science fiction rather than realistic.
Weapons Details
Each weapon name obviously needs to be unique, and keep it short. You'll be using it often when you attach it to vehicles.
Every weapon has a type. For those that do damage the codes are GUN, ROCKET, BOMB, or MISSILE. There is one special code here: RADAR. This defines a radar device that will be used by the AI pilot to detect enemy aircraft based on the range, altitude, and visibility cone values define below.
Regarding the maximum and minimum ranges and altitudes - remember the paragraph above about not putting in unrealistic numbers either too high or too low. AI pilots look at these numbers to decide what weapon to use when and also they greatly influence the calculations for maneuvers since the whole point of air combat is to get within weapons range.
Visibility Cone is quite important. Specifically this is the degrees left or right of the aircraft's current heading in which the weapon can be used. For example, if this cone is defined as 20, then if the aircraft's heading is 200 then the weapon can be used on any enemy (otherwise within range) from a bearing of 220 to a bearing of 180 from the airplane's nose. Typically for ground weapons this cone is 180, which is the maximum number here, representing 360 total degrees. For aircraft this is rarely the case because aircraft weapons are restricted - the only exception usually being the rotating turrets on many vintage level bombers. Aircraft guns have narrow cone of 5 to 10 degrees. For missiles this is particularly important as it limits the firing azimuth - older air-to-air missiles have narrow numbers and newer ones have higher numbers but no missile will have a cone greater than about 50. An AIM-9B or a Shrike will have a very narrow cone of 5 to 10. You can make this number negative, in which case the cone line is behind not ahead of the aircraft. This can be useful for some aircraft that have rear-facing guns.
The Burst, Rounds and Reload data items have a profound effect on what happens when the weapon is fired. FSCAI vehicles (air or ground) take "shots", and roughly at a rate of one "shot" per second. "Burst" is the number of rounds expended per shot, and "Rounds" is the number of rounds in a "magazine." Be aware this applies not only to guns but all weapons. Once the rounds are expended then for a ground vehicle they will have to pause to reload (this gives the targets a short respite) and the "Reloads" data item gives the number of times the magazine can be reloaded until the vehicle is "out of ammo" and has to be re-supplied, which is a lengthy amount of downtime. Aircraft do not get any reloads, when their "Rounds" are used up they are out of ammo even if you give a "Reloads" number for a weapon (remember the same weapon can be attached to an aircraft or a ground vehicle.)
There are some special rules around "Burst" and "Rounds" when talking about bombs to reproduce the way they are dropped in the real world. The "Rounds" is always simply the number of bombs the aircraft is carrying. But "Burst" has some special meaning and this depends on the "Role code" of the aircraft doing the bombing. In short, Attack (A) and Dive Bombers (DB) work differently from Level Bombers (LB). For A and DB types, a "Burst" of 1 means one bomb will be dropped from the centerline store on each attack pass. A "Burst" of 2 means a pair will be dropped from the wings. And any "Burst" above 2 means that number will be dropped per pass from the centerline store. For LB (Level Bomber) roles a "Burst" of 1 means to drop all the bombs in the magazine from the center on the first pass over the target. Any "Burst" above one means to drop that many bombs from the center on each pass.
Accuracy and Potency: These two define how effective the weapon really is. Accuracy is roughly the percentage of the time any shot at the weapon's maximum range will score a direct hit. It is rough because anything can miss. But an accuracy of 100 is extreme - it means the weapon would almost never miss even at maximum range. For guns this accuracy will scale up based on distance such that at a range of 100 meters it will be 100% for for them a low initial maximum range number here would be appropriate. For rockets and bombs this is not relevant - they will either hit or miss based on ballistics. For a missile this is the success rate, in the sense that success means no malfunction will occur. For example a missile with an "accuracy" of 75% would experience guidance or other failures on 25% of shots taken with it. This doesn't mean they will always miss when they fail but the odds of a hit are significantly reduced depending on when in the flight path to the target the failure occurs. It doesn't mean they will always hit when there is no malfunction either - evasive maneuvers and/or countermeasures can still foil them.
Potency is the amount of damage inflicted by a direct hit expressed as a percentage, from 1 to 200. Why over 100? because of the "mitigation" factor on vehicles (see below) that simulates armor. A weapon with a potency of 100 scoring a direct hit on a vehicle with a mitigation of 40 means a 60% hit not a 100% hit. Therefore the maximum is 200, which is a number that will destroy any vehicle in one shot regardless of its mitigation. Any number over 100 is extreme but justified in the case of big bombs like 2000LB and above. This is because of blast radius.
Blast Radius is the diameter of a circle around the impact point of a round in which any SimObject will take damage. The damage is calculated realistically based on distance and the way this is done is to scale the potency. This is why the potency number is for a direct hit. The damage scale is not linear - an object at a distance 50% of the blast radius will take less than 50% of the damage, but it will take some. We should note here the effect of secondary explosions. Any time a truck type vehicle is destroyed there is a random chance that the truck contained ammo, and that ammo may cook off and detonate some time after the initial explosion. This creates another blast radius equivalent to a 500LB bomb. Which in turn can affect other nearby objects and cause more damage which could result in more secondaries and so on. This is why trucks shouldn't be parked close together, ever. But in real life they are sometimes. Further, any time a fuel truck is damaged more than 10% it too will explode in a fireball which again causes secondary damage. The fire will burn for a long time. This is also true for aircraft on the ground which can randomly be loaded with bombs and also have lots of fuel on board. When a bunch are parked together a single bomb hit can cause massive havoc.
SimObject Title is the name of an actual object in the game that will be spawned to visually represent a round from the weapon. Be cautious in the use of this field! Every spawned object costs time and too many can make your sim stutter or even crash. When too many effects are onscreen odd graphic effects sometimes happen. As designers we want to keep performance up so don't put a title on a weapon unless you really need to. A title of "*" means the weapon shoots "invisible bullets" and this is good - no objects are spawned, the program instead calculates the probability of hit or miss based on many factors and inflicts damage based on the results but the amount of time for these calculations is a tiny fraction of the performance hit of having an object flying through the air - because for the sim, every object even tiny nearly invisible ones is an airplane and is treated like an AI airplane piloted by a pilot.
Use the title for missiles, rockets or bombs. In the case of a gun carefully consider whether we need to see tracers coming from it. If it's defined as a "Flak" gun in the special flag code FSCAI will provide the flak explosions as well as calculate the hit percentage based on the accuracy data item. If it's not "Flak" then if you use the "*" FSCAI will not spawn any object so you won't see tracers. If you provide a title to a non-Flak gun then the "Burst" number of tracers will be released each shot. When this happens the program doesn't use its hit probability calculations at all, instead it tracks the tracer and if it hits damage is done (based on Potency) and if it misses, it misses. The "Accuracy" number in this case is used to introduce aiming errors. This is why sometimes "accuracy" is a very rough guide.
Vehicles Details
A vehicle is anything that can move. It can be a truck, tank, ship, or airplane or anything that has an engine.
For any SimObject in the sim world to shoot it must be listed in the FSCAI Vehicle database. What it shoots and how it shoots it depends on the weapon or weapons attached to it, selected from the weapons database. FSCAI does not try to enforce realism. You can define ridiculous weapons and attach them to inappropriate vehicles, the program doesn't care. It's entirely up to you to provide realistic or at least plausible vehicle and weapon definitions.
Vehicle definitions are simple. There aren't too many data items. This causes you to think generically instead of getting lost in details, which is so easy to do in the complex and arcane world of military hardware. Remember what we said at the beginning: KISS: keep it Simple. This database is to serve the purposes of a plausible and realistic AI, not to document the details of real-world weapons. I will repeat that. This database is to serve the purposes of a plausible and realistic AI, not to document the details of real-world weapons.
Resist any urge to get too specific or detailed. It will just make life more complicated for everyone.
The most vital concept to understand is how FSCAI links up a SimObject to a vehicle definition. Every SimObject in the sim world has a data item called Title. The title for each aircraft is defined in the aircraft.cfg file, and for a non-aircraft it's defined in the sim.cfg file. For non aircraft FSCAI uses this title to link to a vehicle. For an aircraft the rule is different (there are good reasons for this.) Every aircraft in the sim world also has an "atc_model" code assigned to it in the aircraft.cfg. As far as the sim goes this "atc_modeL' is used to help the built-in ATC system call the airplane by it's right model. For example a model code of "B737" would allow the ATC controllers to say "seven thirty seven" when they refer to the aircraft. Because this model code is the closest thing to a type of aircraft we have available to us, FSCAI uses it to link to aircraft vehicle types in the database.
If we used the "Title" then every single livery or paint would have to be defined in the database. But by using the model we get around this: a "P51" is a "P51" regardless of how it's painted. Why not use the model code for ground vehicles then? Because the sim.cfg fiel they are defined with typically does not allow an "atc_model" to be defined for them. We have to use Title, but this is not a major problem because there are rarely multiple paints for ground vehicles in practice.
Therefore because of this, aircraft and non-aircraft are defined a little differently. Let's talk about aircraft first.
Every vehicle has an official name and it must be unique but you can use anything you want in this field. I recommend keeping it short.
After the official name you must list the atc_model for this aircraft definition. It should be unique too -- there is no point in defining the same model twice, only the first would ever be used. This is used to match to the atc_model defined in the aircraft.cfg as mentioned above. No match, no weapons. You will need to look in the aircraft.cfg for "atc_model=" for new airplanes and use the code there, or change it in that file to match.
For an aircraft the vehicle type must be aircraft - obviously.
Damage Mitigation is rarely used for aircraft, they are all pretty fragile. For some that have a reputation of being tough I put a small number here like 5. This will prevent a weapon with a potency of 100 (for example a missile) from outright destroying it with one hit. It will be almost destroyed at 95% but still can be flown. Beware putting higher numbers in here - even "tough" aircraft will fall to a direct hit from most missiles.
Normal cruising speed isn't really used - we use the design cruising speed defined in the aircraft.cfg instead. But you need to put something reasonable here, because it will be used if the speed in the aircraft.cfg is missing or unreasonable (which some actually are).
Visibility Cone is quite important. Specifically this is the degrees left or right of the aircraft's current heading in which the pilot can normally see another aircraft. This is a major factor in finding enemies and avoiding disaster. Remember this is the degrees to the left and to the right, not both! The maximum value is 180, which would be a 360 degree circle with no blockage. This is not realistic! Almost every airplane has some blockage to the rear vision, even with mirrors - and mirrors distort and aren't effective unless the enemy is close behind you. Some aircraft have more than others - for instance the famous MiG-21 has very poor rear visibility. Thus is is defined with a restrictive cone of 110, whereas a more modern bubble cockpit has a typical cone of about 160. This is not an absolute block! All pilots can "check six" periodically (rate determined by their skill rating) but if an enemy is within this cone he will be picked up much quicker.
The Role Code is used to generically define the aircraft's combat role. Since aircraft don't use a Title to match up we have taken over this data item for the Role Code. The purpose of this code is so the AI pilot can understand the typical combat role his aircraft plays. This affects many of his decisions and defining an appropriate role code is vital. The codes are:
- A - Attack Aircraft. This is an aircraft designed to strike ground targets. Although it may have some defensive air-to-air capabilities that's not its purpose and not what it's good at. Examples would be most US aircraft whose model starts with "A" like the A-1 Skyraider, A-4 Skyhawk, or A-10 warthog. Or the Russian Su-25 is another good example. It will always have a primary air-to-ground weapon defined and usually many more.
- F - Fighter Aircraft. This is designed to shoot down other aircraft in an air superiority role. It will always have a primary air-to-air weapon defined and often more on modern airplanes.
- FB - Fighter/Bomber. One that swings both ways. Typically a jack of both trades but master of neither. It can be difficult to decide between F and FB for some aircraft, like the P-51 which served both roles. It's not a huge deal which you pick actually.
- DB - Dive Bomber. An Attack aircraft that uses a steep dive as its primary method of bomb release. A Stuka or Douglas Dauntless or many other examples.
- LB - Level Bomber. An Attack aircraft that's designed to release typically large bomb loads in level flight.
- T - Transport. A typically unarmed transport aircraft, usually large. It may have defensive weapons which is why we allow it to be defined here. An AWACS aircraft would be defined as a T type, but would be equipped with a radar device for detection of enemy aircraft.
Vehicle Weapons - this is where you list the weapons attached to the vehicle. There are 8 "slots". Slot #1 should be reserved for the primary air-to-air weapon, and slot #2 should be reserved for the primary air-to-ground weapon. Either can be used for any weapon however. Weapons are selected by the AI pilot in a primary order defined by the slot position. Lower slots are selected over higher numbered ones. Only when a lower numbered slot is out of ammo or out of range will an AI pilot select a higher numbered one.
Now we'll talk about ground vehicles - which includes ships.
These vehicles don't use the atc_model code to match up, so that data item can be used for a "Short name".
The "Vehicle Type" can be a wide select; anything but "Aircraft". This isn't used much in the present release, but when we start to have ground vehicles engaging one another it's going to matter a great deal.
Damage Mitigation is very important for ground vehicles - it's how we distinguish between soft and hard targets. A truck has zero mitigation, whereas a tank could have up to 50 or more. Be wary of extreme numbers here. Remember this is matched against weapon potency to determine damage in a direct hit. For example let's say an AGM-65 Maverick has a potency of 100. Let's also say a tank that it targets has a mitigation of 50. That means a direct hit by the Maverick would reduce the tank by 50%, barely disabling it but it would survive. That's not totally unrealistic, although a mitigation for 30 or 40 would be better. A mitigation of 80 would allow a vehicle to not only survive a direct AGM-65 hit but not even be disabled - NOT realistic.
Cruising speed is important for surface vehicles, as we have no other source for this number.
Visibility Cone works just like it does for aircraft, but typically it is 180 for ground vehicles specially anti-aircraft weapons.
The "Role Code" data item for aircraft is the SimObject Title for ground vehicles. This is used to weaponize a particular ground vehicle or ground of vehicles with the same title in the same world. No match, no shooting. This title can be found in the sim.cfg in the vehicle's folder, or sometimes a ground vehicle is defined as an aircraft - in this case look in the aircraft.cfg. In both cases what you are searching for is "Title=" - case doesn't matter.
I hope this has been useful.
Dutch